home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Tools / MPW / lgrind 1.0.1 / lgrind.1 < prev    next >
Encoding:
Text File  |  1993-04-22  |  7.2 KB  |  242 lines  |  [TEXT/MPS ]
  1. '\" t
  2. '\" $Id: lgrind.1,v 1.2 91/10/01 00:42:26 gvr Exp $
  3. '\" This man page was reverse engineered by George V. Reilly from the
  4. '\" preformatted man page written by Tuna Ertemalp for Jerry Leichter's
  5. '\" version of tgrind.  gvr remains wilfully ignorant of troff.
  6. .ds C C\"    \" Fixed-width font
  7. .TH lgrind 1
  8. .SH NAME
  9. lgrind \- grind nice program listings using LaTeX
  10. .SH SYNOPSIS
  11. lgrind [ \fB-e\fP ] [ \fB-i\fP ] [ \fB-\fP ] [ \fB-n\fP ]
  12. [ \fB-h\fP \fI<header>\fP ] [ \fB-d\fP \fI<description file>\fP ]
  13. [ \fB-l\fP\fI<language>\fP ] \fI<name>\fP ...
  14. .PP
  15. .SH DESCRIPTION
  16. Lgrind formats program sources in a nice style using (La)TeX(1).
  17. Comments are placed in roman, keywords in bold face, variables in
  18. italics, and strings in typewriter font. Source file line numbers
  19. appear in the right margin (every 10 lines).
  20. .PP
  21. Lgrind processes its input file(s) and writes the result to standard
  22. output.  This output can be saved for later editting, inclusion in a
  23. larger document, etc.
  24. .PP
  25. The options are:
  26. .IP "\fB\-e\fP"
  27. process a LaTeX file for embedded text.
  28. .IP "\fB\-i\fP"
  29. process for inclusion in a LaTeX document.
  30. .IP "\fB\-\fP"
  31. take input from standard input.
  32. .IP "\fB\-n\fP"
  33. don't boldface keywords.
  34. .IP "\fB\-h\fP"
  35. specifies text to go on the left side of every output page (default is none).
  36. .IP "\fB\-d\fP"
  37. specifies the language definitions file (default is
  38. \fB/cs/lib/lgrindefs\fP).
  39. .IP "\fB\-l\fP"
  40. specifies the language to use.  Currently known are
  41. C (\fB\-lc\fP or the default),
  42. C++ (\fB\-lc++\fP or \fB\-lCC\fP),
  43. PASCAL (\fB\-lp\fP),
  44. Modula-2 (\fB\-lm2\fP),
  45. Fortran (\fB\-lf\fP),
  46. RATFOR (\fB\-lr\fP),
  47. Yacc (\fB\-ly\fP),
  48. PostScript (\fB\-lps\fP),
  49. Prolog (\fB\-lprolog\fP),
  50. MLisp (\fB\-lmlisp\fP),
  51. Icon (\fB\-lI\fP),
  52. TeX (\fB\-ltex\fP),
  53. Metafont (\fB\-lmf\fP),
  54. Perl (\fB\-lperl\fP),
  55. CSH (\fB\-lcsh\fP),
  56. Bourne Shell (\fB\-lsh\fP)
  57. assembler (\fB\-lasm\fP),
  58. 68000 assembler (\fB\-la68\fP),
  59. asm68 (\fB\-lasm68\fP),
  60. VMS assembler (\fB\-lvmsasm\fP),
  61. ISP (\fB\-lisp\fP),
  62. LDL (\fB\-lldl\fP),
  63. Linda (\fB\-llinda\fP),
  64. MODEL (\fB\-lm\fP),
  65. and
  66. Russell (\fB\-lrussell\fP).
  67. .PP
  68. If neither \fB\-e\fP nor \fB\-i\fP are specified, a complete LaTeX
  69. file is produced.
  70. .SH USAGE
  71. For example, to include a C file named \fCfoo.c\fP into your LaTeX
  72. document, first give the command:
  73. .IP "\fC    lgrind -i -lc foo.c > foo.tex\fP"
  74. .PP
  75. This will generate \fCfoo.tex\fP, which will have the
  76. pretty-printed version of \fCfoo.c\fP with a lot of LaTeX commands.
  77. .PP
  78. Then include \fClgrind.sty\fP as you include any other style,
  79. namely with the \fC\edocumentstyle[...,lgrind,...]{...}\fP line at
  80. the beginning of your LaTeX document. Having done this,
  81. within the document you can include \fCfoo.tex\fP using one of the
  82. following commands:
  83. .PP
  84. .IP "\fC\elgrindfile{foo.tex}\fP"
  85. which will simply include the file at that point
  86. of text, and will draw horizontal lines before and
  87. after the listing.
  88. .PP
  89. .IP "\fC\elagrind[htbp]{foo.tex}{caption}{label}\fP"
  90. which will put the listing also within a figure
  91. environment, using the float options, caption and
  92. label you gave.
  93. .PP
  94. To produce a standalone LaTeX file from, say, a Yacc file:
  95. .IP "\fC    lgrind bary.y > bary.tex\fP"
  96. This uses Piet van Oostrum's \fCfancyheadings.sty\fP to make the
  97. headers and footers.
  98. .PP
  99. For a more detailed explanation of these commands, refer to
  100. \fC/cs/lib/tex/inputs/lgrind.doc\fP.
  101. .PP
  102. .SH "EMBEDDED PROGRAMS WITHIN A LaTeX FILE"
  103. (From Jerry Leichter's notes.)
  104. .PP
  105. Within the text of your LaTeX file, you mark groups of lines as
  106. either text- or display-style program code:
  107. .PP
  108. Text style:
  109. .TS
  110. l l.
  111. .ft \*C
  112.     The expression
  113.     %(
  114.     a + 3
  115.     %)
  116.     produces 10.
  117. .ft
  118. .TE
  119. prints something like:  "The expression \fIa\fP + 3 produces 10."
  120. (with "a + 3" set as a program.)
  121. .PP
  122. The same effect can be achieved with inline @'s.
  123. .TS
  124. l l.
  125. .ft \*C
  126.     The expression @a + 3@ produces 10.
  127. .TE
  128. .PP
  129. Display style:
  130. .TS
  131. l l.
  132. .ft \*C
  133.     The statement
  134.     %[
  135.     a += 3;
  136.     %]
  137.     is an example of an incrementing operator.
  138. .ft
  139. .TE
  140. prints something like:
  141. .TS
  142. l l.
  143.     The statement
  144.           a += 3;
  145.     is an example of an incrementing operator.
  146. .TE
  147. .PP
  148. Important rules:
  149. .IP
  150. \fC%\fP and the following character must be the first two characters on
  151. the line to be recognized.
  152. .IP
  153. Put \fInothing\fR on the line after the \fC%\fR and the key character.
  154. If you do that, lgrind will provide a default environment that will
  155. produce an \fC\ehbox\fP for \fC%(\fP \fC)%\fP, and a \fC\evbox\fP for
  156. \fC%[\fP \fC-\fP \fC%]\fP.  If you put stuff on the line, lgrind
  157. assumes you want to control the format completely.  Doing this
  158. requires understanding \fIexactly\fP what the code lgrind produces is
  159. doing. (Sometimes I'm not sure I do!)
  160. .IP
  161. \fC%)\fP and \fC%]\fP are, if I remember right, simply ignored outside
  162. of a code group, but any extra \fC%(\fP or \fC%[\fP produces a
  163. warning, so a missing \fC%)\fP or \fC%]\fP is usually caught.
  164. .PP
  165. You can insert your own code by using a line starting with \fC%=\fP in
  166. the program text.  Whatever you enter after that is left in the
  167. output, exactly as you typed it.  It will be executed in a strange
  168. environment, so doing anything fancy is very tricky.  A macro, \fC\eLine\fP,
  169. is provided to help you do simple things.  For example,
  170. .TS
  171. tab (/);
  172. l.
  173. .ft \*C
  174. %[
  175. %=\eLine{________\evdots}
  176.         a = 1;
  177. %]
  178. .ft
  179. .TE
  180. produces:
  181. .TS
  182. tab (/);
  183. l.
  184. .ft \*C
  185.         \.
  186.         \.
  187.         \.
  188.         a = 1;
  189. .ft
  190. .TE
  191. .PP
  192. (Within the program text, \fC_\fP is active and expands to a
  193. fixed-width space.  A whole bunch of macros are also defined.  If you
  194. understand how lgrind sets lines up, you can replace the 8 \fC_\fP's
  195. with a call to \fC\eTab\fP \(em but I'll let you hang yourself on that one.)
  196. .PP
  197. The output of lgrind always contains exactly one output line for each input
  198. line.  Hence, you can look up line numbers in TeX error messages in your
  199. original file, rather than in the lgrind'ed (lground?) file.  (Of course, if
  200. the problem is in the lgrind output....)
  201. .PP
  202. '\" The environment that lgrind's output builds uses a \fIlot\fP of
  203. '\" stack space.  I found I had to build a LaTeX with a larger stack,
  204. '\" but that's not always necessary \(em it depends on exactly how you
  205. '\" nest stuff.
  206. '\" .PP
  207. Many things are controllable by re-defining various macros.  You can
  208. change what fonts lgrind will use for various kinds of things, how
  209. much it indents the output, whether it adds line numbers, and if so at
  210. what interval it prints them and whether it sticks them on the left or
  211. right, and so on.  This stuff is all described in \fClgrind.doc\fP,
  212. though probably not very well. The default settings produce output
  213. that looks reasonable to me, though I can't say I'm ecstatic about it.
  214. Doing a \fIreally\fP good job would require defining some special fonts.
  215. .PP
  216. .SH FILES
  217. .IP "\fC/cs/bin/lgrind\fP"
  218. Executable
  219. .PP
  220. .IP "\fC/cs/lib/tex/inputs/lgrind.doc\fP"
  221. Documented LaTeX style file
  222. .PP
  223. .IP "\fC/cs/lib/tex/inputs/lgrind.sty\fP"
  224. LaTeX style file
  225. .PP
  226. .IP "\fC/cs/lib/lgrindefs\fP"
  227. Language descriptions
  228. .PP
  229. .SH AUTHOR
  230. Van Jacobson, Lawrence Berkeley Laboratory (based on
  231. "vgrind" by Dave Presotto & William Joy of UC Berkeley),
  232. wrote it for TeX.
  233. .PP
  234. Jerry Leichter of Yale University modified it for LaTeX.
  235. .PP
  236. George V. Reilly of Brown University changed the name to lgrind,
  237. fixed up the man page, and added the program-text-within-comments
  238. and @-within-LaTeX features.
  239. .PP
  240. .SH "SEE ALSO"
  241. latex(1), tex(1), vgrind(1), lgrindefs(5)
  242.